.TH RPCFCTL 1 "July 2025" "rpc-frmwrk" "Application Control Utility Manual"

.SH NAME
rpcfctl \- rpc-frmwrk Application Control Utility

.SH SYNOPSIS
.B rpcfctl
<command> [arguments]

.SH DESCRIPTION
.B rpcfctl
is a command-line utility for managing applications, users, groups, authentication, and security settings in the rpc-frmwrk framework. It provides commands to start, stop, restart, check status, and list applications, as well as to add, remove, and initialize the application and user registries. It also supports SSL key/cert management, authentication, and configuration for web and Kerberos integration.
.PP
In addition to application and registry management, 
.B rpcfctl
provides commands for simple point log management, including backup, rotation, listing, and enabling/disabling logs for managed applications.

.SH COMMANDS
.TP
.B start <appname>
Start the application \fIappname\fR.
.TP
.B stop <appname>
Gracefully stop the application \fIappname\fR (SIGINT).
.TP
.B kill <appname>
Forcefully stop the application \fIappname\fR (SIGKILL).
.TP
.B restart <appname>
Restart the application \fIappname\fR.
.TP
.B status <appname>
Show status of the application \fIappname\fR.
.TP
.B list
List all the registered applications and their status.
.TP
.B startall
Start all managed applications (core services first).
.TP
.B stopall
Stop all managed applications (core services last).
.TP
.B restartall
Restart all managed applications.
.TP
.B addapp <appname>, add <appname>
Add a new application \fIappname\fR to the app registry.
.TP
.B cloneapp <appname> <new appname>
Clone an existing app <appname> to <new appname>.
.TP
.B rmapp <appname>, rm <appname>
Remove the application \fIappname\fR from the app registry.
.TP
.B showapp <appname>
Show detailed information for the application \fIappname\fR.
.TP
.B addpoint <appname> <point name> <point type> <value type>
Add a new point to the app <appname>, with <point type> to be one of input, output, or setpoint, and value type to be one of b(byte), w(word), i(int), q(int64),d(double), f(float), s(string, less than 94 chars ), blob.
.TP
.B rmpoint <appname> <point name>
Remove a point from the app <appname>.

.TP
.B setpv <appname> <point name> <point type> <value>
Set a property value for the specified application.
.TP
.B getpv <appname> <point name>
Get a property value for the specified application.
.TP
.B setattr [-f] <appname> < point name> <attribute> <attr type> <value>
Set an attribute for the specified application. <attr type> can be b(byte), w(word), i(int), q(int64),d(double), f(float), s(string, less than 94 chars ), blob. The '-f' is valid if type is blob, and the <value> must be a file path and the content is the value is of the attribute. the file size should be less than 8MB.
.TP
.B getattr <appname> <point name> <attribute>
Get an attribute for the specified application.
.TP
.B addlink <output app> <output point> <input app> <input point>
Add a link between a pair of output and input points in the registry.
.TP
.B rmlink <app1> <point1> <app2> <point 2>
Remove a link between a pair of output and input points in the registry. There is no restriction whether the input or output point goes first.
.TP
.B initappreg
Initialize (clear) the app registry. \fBWARNING:\fR This will clear your app registry.
.TP
.B initusereg
Initialize (clear) the user registry. \fBWARNING:\fR This will clear your user registry.
.TP
.B initsvr
Initialize both the app and user registries on the server side.
.TP
.B initcli
Initialize the client registry on the client side.
.TP
.B importkey <openssl|gmssl> <private key> <public cert> [<cacert file>]
Import SSL keys and certificates for rpc-frmwrk.
.TP
.B genkey <openssl|gmssl> <#client keys> <#server keys> [<DNS name>]
Generate self-signed public/private key and certificate pairs.
.TP
.B printcert <openssl|gmssl> <cert file>
Print details of a certificate file.
.TP
.B adduser <user name>
Add a user to the user registry.
.TP
.B rmuser <user name>
Remove a user from the user registry.
.TP
.B showuser <user name>
Show details for a user.
.TP
.B listuser
List all users in the user registry.
.TP
.B addgroup <group name>
Add a group to the group registry.
.TP
.B rmgroup <group name>
Remove a group from the group registry.
.TP
.B showgroup <group name>
Show details for a group.
.TP
.B listgroup
List all groups in the group registry.
.TP
.B joingroup <group name> <user name>
Add a user to a group.
.TP
.B leavegroup <group name> <user name>
Remove a user from a group.
.TP
.B backuplog [<output file>]
Backup all application log files into a tarball. If <output file> is not specified, a default name (such as rpcf-logbackup-YYMMDD.tar.gz) will be used.
.TP
.B rotatelog <appname> <point name>
Rotate the log file for the specified setpoint.
.TP
.B listlog <appname> <point name>
List all log files for the specified setpoint
.TP
.B enablelog <appname> <point name>
Enable logging for the specified setpoint.
.TP
.B disablelog <appname> <point name>
Disable logging for the specified setpoint.
.TP
.B authmech
Show the current authentication mechanism in use.
.TP
.B login [arguments]
Authenticate the user using the mechanism specified in driver.json.
.RS 4
.TP
.B SimpAuth(Password)
 'login' saves the credential in a secure place, and enables non-js client to
 connect to rpc-frmwrk server from command line. JS client will login from the
 browser.
.TP
.B Kerberos
 'login' performs the preauth login with 'kinit', to get the ticket-grant-ticket
 from KDC.
.TP
.B OAuth2
 'login' will initiate the authorization-code-grant process to get a security
 token (not the access token) from rpc-frmwrk. With which, the non-js client can
 connect to the rpc-frmwrk.
.RE
.TP
.B geninitcfg [-c] [<output file>]
Generate a config file 'initcfg.json' for current system settings. It is for
debug purpose or as input for command 'geninstaller'.  If no <output file>
specified, geninicfg will print 'initcfg.json' to the standard output. if '-c' is
specified, the 'initcfg.json' is for client only.
.TP
.B geninstaller <path to initcfg> <path to put installer files> [<directory of rpc-frmwrk deb/rpm packages>]
Generate installers for deployment using current
system settings. Usually it will generate a pair of installers, one for server
and one for client. If 'initcfg.json' is client only, a single client installer
will be generated. If the target settings is quite different from the current
settings, you can manually edit the 'initcfg.json', or using 'rpcfg.py' to
generate the installer. When editing 'initcfg.json', please 
.B DON'T
make change to file paths, which is needed by geninstaller and will be corrected
before installation.
.TP
.B updcfg <path to initcfg>
Update the local rpc-frmwrk installation's configurations with the specified
`initcfg.json'. It is convenitent to update the rpc-frmwrk's configurations
after manually modified the initcfg.json, as output from command 'geninitcfg'.
.TP
.B cfgweb
Update web server configuration (nginx or apache) using current rpc-frmwrk configuration.
.TP
.B cfgkrb5
Update Kerberos configuration using current rpc-frmwrk configuration.
.TP
.B backup 
Backup server-side settings. The output is a tarball named rpcf-backup-YYMMHH.tar.gz command line is 'rpcfctl backup'.
.TP
.B restore 
Restore the server-side settings from a tarball. Command line is 'rpcfctl restore <backup file>'
.TP
.B -h, --help
Show help message and exit.

.SH EXAMPLES
.TP
Start an application:
.B
rpcfctl start myapp
.TP
Set a point value:
.B
rpcfctl setpv abcapp mypoint i 0 (set the value to an integer 0 of the point 'abcapp/mypoint' ) 
.TP
Get the value of an attribute:
.B
rpcfctl getattr abcapp mypoint ptype (get the value of attribute 'ptype')
.TP
Add a link between a pair of input/output points:
.B
rpcfctl addlink abcapp1 algout abcapp2 algin
.TP
Import SSL keys:
.B
rpcfctl importkey openssl /path/to/key.pem /path/to/cert.pem /path/to/cacert.pem
.TP
Generate initial web config:
.B
rpcfctl geninitcfg > /tmp/initcfg.json
.TP
Authenticate user:
.B
rpcfctl login alice

.SH FILES
.TP
.B showapp.sh, getpv.sh, setpv.sh, listapps.sh, addapp.sh, rmapp.sh, initappreg.sh, inituser.sh, updattr.py, updatekeys.py, rpcfaddu.sh, rpcfrmu.sh, rpcfshow.sh, rpcfaddg.sh, rpcfrmg.sh, rpcfmodu.sh, updwscfg.sh, updk5cfg.sh, sinit, oinit.py, rpcfg.py.
Helper scripts used by rpcfctl, typically located in the same directory of rpcfctl or the 'rpcf' sub-directory.

.SH SEE ALSO
.BR appmonsvr (1),
.BR rpcrouter (1),
.BR regfsmnt (1)

.SH AUTHOR
Ming Zhi <woodhead99@gmail.com>

.SH LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation at http://www.gnu.org/licenses/gpl-3.0.html
